The topic interface is accessed
principally via the command woman. The same command
can be accessed via the menu item ‘Help->Manuals->Read Man Page
(WoMan)...’ once WoMan has been loaded. The
command reads a manual topic in the minibuffer, which can be the
basename of a man file anywhere in the man file
structure. The “basename” in this context means the
filename without any directory component and without any
extension or suffix components that relate to the file type. So,
for example, if there is a compressed source file in Chapter 5 of
the UNIX Programmer's Manual with the full pathname
/usr/local/man/man5/man.conf.5.gz then the
topic is man.conf. Provided WoMan is configured
correctly, this topic will appear among the completions offered
by woman. If more than one file has the same topic
name then WoMan will prompt for which file to format. Completion
of topics is case insensitive.
Clearly, woman has to know where to look for man
files and there are two customizable user options that store this
information: woman-manpath and
woman-path. See Interface Options.
If woman-manpath is not set explicitly then WoMan
tries to pick up the information that would be used by the
man command, as follows. If the environment variable
MANPATH is set, which seems to be the standard
mechanism under UNIX, then WoMan parses that. Otherwise, if WoMan
can find a configuration file named (by default)
man.conf (or something
very similar), which seems to be the standard mechanism under
GNU/Linux, then it parses that. To be precise, “something
very similar” means starting with ‘man’ and ending with
‘.conf’ and
possibly more lowercase letters, e.g. manual.configuration. The search path and/or
precise full path name for this file are set by the value of the
customizable user option woman-man.conf-path. If all
else fails, WoMan uses a plausible default man search path.
If the above default configuration does not work correctly for
any reason then simply customize the value of
woman-manpath. To access man files that are not in a
conventional man file hierarchy, customize the value of
woman-path to include the directories containing the
files. In this way, woman can access manual files
anywhere in the entire file system.
There are two differences between woman-manpath
and woman-path. Firstly, the elements of
woman-manpath must be directories that contain
directories of man files, whereas the elements of
woman-path must be directories that contain man
files directly. Secondly, the last directory component
of each element of woman-path is treated as a
regular (Emacs) match expression rather than a fixed name, which
allows collections of related directories to be specified
succinctly. Also, elements of woman-manpath can be
conses, indicating a mapping from ‘PATH’ environment variable components
to man directory hierarchies.
For topic completion to work, WoMan must build a list of all
the manual files that it can access, which can be very slow,
especially if a network is involved. For this reason, it caches
various amounts of information, after which retrieving it from
the cache is very fast. If the cache ever gets out of synchronism
with reality, running the woman command with a
prefix argument (e.g. C-u M-x woman) will force it to
rebuild its cache. This is necessary only if the names or
locations of any man files change; it is not necessary if only
their contents change. It would always be necessary if such a
change occurred whilst Emacs were running and after WoMan has
been loaded. It may be necessary if such a change occurs between
Emacs sessions and persistent caching is used, although WoMan can
detect some changes that invalidate its cache and rebuild it
automatically.
Customize the variable woman-cache-filename to
save the cache between Emacs sessions. This is recommended only
if the woman command is too slow the first time it
is run in an Emacs session, while it builds its cache in main
memory, which may be very slow. See The WoMan Topic Cache, for further
details.